showtext

Section: User Commands (1)
Updated: Sep 1995
Index Return to Main Contents
 

NAME

showtext - interpret and show text through ncurses  

SYNOPSIS

showtext [-v]

showtext showtext-file  

DESCRIPTION

This is a interpreter for simple text files mixed with some special commands and attributes. The output can be directed to dump terminals or through ncurses on more intelligent terminals.

It is a approach to simplify and beautify simple scripts for use in a bbs, but can be used for other things too, of course.

The commands and attributes are included as tokens in square brackets. See TOKENS below.

Most commands interpret their arguments, i.e. showtext substitutes constructs such as $name with the content of variable "name" (see SYSTEM VARIABLES below) and %ename with the content of environment variable "ename". Text in backquotes `` is piped to the shell for execution and the stdout is substituted. Be very careful with this option, showtext will not check the length of the value and in a case of overflow it will exit or start doing silly things.

Commands beginning with "if" test some condition and execute the remainder of the line if the condition is true or skip to the next line if not.

Normal text is printed as it is found, including line feeds. For that reason it may be necessary to quote line feeds by putting a \ at the end of a line.

Quoting is also used to print special characters ( "[", "$", "%", "`" and "@" ) without interpreting and to output special characters like \a (alarm), \b (backspace), \f (formfeed), \n (newline), \r (carriage return), \t (horizontal tabulator) and \v (vertikal tabulator). \a, \f, \v will be printed as literals in ncurses mode.

Color attributes will be ignored on terminals not capable to show colors. A lot of commands have only effect in curses mode (or better ncurses mode).

Comment lines can be included by putting a # in the first column.  

OPTIONS

-v
show version and exit.
 

TOKENS

CLS
clear screen in curses mode
TERM
switch to curses mode, enable color mode if possible
R or REFRESH
update screen in curses mode (this is needed when in curses mode, otherwise no screen output will occur, see ncurses(3))
exit
quit current instance of showtext
wait text or warte text
optionally print text and wait for a carriage return
NOTERM
switch to normal tty mode (end curses mode)
go_x x
goto horizontal position x in curses mode
go_y y
goto vertical position y in curses mode
c_eol
clear to end of line in curses mode
c_bot
clear to screen bottom in curses mode
goto label
jump to label in showtext file
blink
set blink attribute in curses mode
noblink
unset blink attribute in curses mode
bold
set bold attribute in curses mode
nobold
unset bold attribute in curses mode
normal
switch off attributes - normal color
black, red, green, brown, blue, magenta, cyan, lgray, gray, dgray, lred, lgreen, yellow, lblue, lmagenta, lcyan, white
set foreground to named color, gray is the same as lgray
bg color
set background to color, see above (bright colors are not available)
reverse or inverse
set reverse attribute (kills color attribute !)
noreverse or noinverse
unset reverse attribute
login
print login name
env var
print environment variable var
system command
executes shell command (binary or script); output will be just put on the screen in stdout mode, so better place a [R] in front (see PROBLEMS below).
exec command
executes command (no return !)
spawn command
creates another process and executes command
pipe command
executes command and stores output
ppipe command
same as pipe but prints output immediatly
opipe
prints output of previous pipe command
getkey charlist
get characters until in character list
okey
print character from previous getkey command
getstr length name
get string in variable name with max length characters
igetstr name
get string into variable name
ostr var
print out variable var
ostrc var
like ostr, but centers output in curses mode
ostri var
interprets argument (variable substitution) and outputs result
open file
opens text file file for output (truncates existing file to zero size)
append file
opens text file file for output (appends to existing file)
iopen file
opens text file file for input
close
close file from previous open/append
iclose
close file from previous iopen
irewind
position file pointer of input file to beginning
redir
redirects following output commands to output file (open/append)
unredir
redirect back to stdout
set var value
set variable var to value (w/ var substitution)
unset var
unset variable var
truncr var
truncates trailing spaces from variable var
truncl var
truncates leading spaces from variable var
advance var value
add value to variable var
ifexist file
executes remainder of line if file file exists
ifterm type
dito if terminal type is type
ifempty var
dito if variable var is empty (zero length)
ifnempty var
dito if variable var is not empty (length >0)
ifzero var
dito if variable var is zero (numerical comparison)
ifnzero var
dito if variable var is not zero (numerical comparison)
ifeq var value
dito if variable var is equal to value
ifneq var value
dito if variable var is not equal to value
ifgt var value
dito if variable var is greater than value (numerical comparison)
ifngt var value
dito if varaible var is not greater than value (numerical comparison)
pause number
executes wait if less than number lines left
include file
includes file into current showtext file
 

SYSTEM VARIABLES

_boxtime
time limit for the session in minutes
_curx
current column of current screen
_cury
current line of current screen
_error
errno from previous open/iopen/append
_hour
actual time hour [0-23]
_key
character from last getkey command (case insensitive, always lower case)
_Key
like _key, but case sensitive
_left
time left for current session in minutes
_level
access level - environment variable boxlevel
_logon
time user logged on in time_t format
_maxx
max columns in current screen
_maxy
max lines in current screen
_min
actual time minutes [0-59]
_pid
process id of current showtext process
_term
terminal type - environment variable TERM
_time
actual time in time_t format
_wait
prompt to use for wait (defaults to "more ")
 

ENVIRONMENT VARIABLES

Print content of an environment variable :

%name
where name is an environment variable

Showtext uses some environment variables for managing user access and time limits :

TERM terminal type

boxlevel user access level - may be set in user profile and checked in showtext

logon_time logon time of the user in time_t format - for calculation of the online time

boxtime time limit in minutes

SHOWPATH path to showtext files  

FILES

/usr/local/bin/showtext
the showtext binary
/usr/lib/box/
default search path for showtext files (may be overwritten by SHOWPATH environment variable)
 

COPYING

See GPL and copyright notice in source code.  

PROBLEMS

Some strange things can happen when showtext mixes output in stdout mode (for example a [system ] with ncurses mode. As ncurses buffers until explicit told to output, the order of mixed output is random. To prevent this, put a [R] in front of a [system ] when output will occur.

Substituting and setting variables is a bit risky, see BUGS below. Be careful with substituting ` ` terms.  

BUGS

Filling variables has no range check, so showtext may seg fault on this. Variables have a default maximum length configurable in show.h when built.  

SEE ALSO

ncurses(3)  

AUTHOR

Rolf Jakob <rjakob@duffy1.franken.de>


 

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
TOKENS
SYSTEM VARIABLES
ENVIRONMENT VARIABLES
FILES
COPYING
PROBLEMS
BUGS
SEE ALSO
AUTHOR

This document was created by man2html, using the manual pages.
Time: 15:51:28 GMT, November 05, 2024